home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / Tk / fileevent.z / fileevent
Encoding:
Text File  |  1998-10-30  |  6.9 KB  |  133 lines
  1.  
  2.  
  3.  
  4. ffffiiiilllleeeeeeeevvvveeeennnntttt((((3333TTTTkkkk))))                                                  ffffiiiilllleeeeeeeevvvveeeennnntttt((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      fileevent - Execute a script when a file becomes readable or writable
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ffffiiiilllleeeeeeeevvvveeeennnntttt _f_i_l_e_I_d rrrreeeeaaaaddddaaaabbbblllleeee ?_s_c_r_i_p_t?
  13.      ffffiiiilllleeeeeeeevvvveeeennnntttt _f_i_l_e_I_d wwwwrrrriiiittttaaaabbbblllleeee ?_s_c_r_i_p_t?
  14.  
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      This command is used to create _f_i_l_e _e_v_e_n_t _h_a_n_d_l_e_r_s.  A file event handler
  18.      is a binding between a file and a script, such that the script is
  19.      evaluated whenever the file becomes readable or writable.  File event
  20.      handlers are most commonly used to allow data to be received from a child
  21.      process on an event-driven basis, so that the receiver can continue to
  22.      interact with the user while waiting for the data to arrive.  If an
  23.      application invokes ggggeeeettttssss or rrrreeeeaaaadddd when there is no input data available,
  24.      the process will block;  until the input data arrives, it will not be
  25.      able to service other events, so it will appear to the user to ``freeze
  26.      up''.  With ffffiiiilllleeeeeeeevvvveeeennnntttt, the process can tell when data is present and only
  27.      invoke ggggeeeettttssss or rrrreeeeaaaadddd when they won't block.
  28.  
  29.      The _f_i_l_e_I_d argument to ffffiiiilllleeeeeeeevvvveeeennnntttt refers to an open file; it must be
  30.      ssssttttddddiiiinnnn, ssssttttddddoooouuuutttt, ssssttttddddeeeerrrrrrrr, or the return value from some previous ooooppppeeeennnn
  31.      command.  If the _s_c_r_i_p_t argument is specified, then ffffiiiilllleeeeeeeevvvveeeennnntttt creates a
  32.      new event handler:  _s_c_r_i_p_t will be evaluated whenever the file becomes
  33.      readable or writable (depending on the second argument to ffffiiiilllleeeeeeeevvvveeeennnntttt).  In
  34.      this case ffffiiiilllleeeeeeeevvvveeeennnntttt returns an empty string.  The rrrreeeeaaaaddddaaaabbbblllleeee and wwwwrrrriiiittttaaaabbbblllleeee
  35.      event handlers for a file are independent, and may be created and deleted
  36.      separately.  However, there may be at most one rrrreeeeaaaaddddaaaabbbblllleeee and one wwwwrrrriiiittttaaaabbbblllleeee
  37.      handler for a file at a given time.  If ffffiiiilllleeeeeeeevvvveeeennnntttt is called when the
  38.      specified handler already exists, the new script replaces the old one.
  39.  
  40.      If the _s_c_r_i_p_t argument is not specified, ffffiiiilllleeeeeeeevvvveeeennnntttt returns the current
  41.      script for _f_i_l_e_I_d, or an empty string if there is none.  If the _s_c_r_i_p_t
  42.      argument is specified as an empty string then the event handler is
  43.      deleted, so that no script will be invoked.  A file event handler is also
  44.      deleted automatically whenever its file is closed or its interpreter is
  45.      deleted.
  46.  
  47.      A file is considered to be readable whenever the ggggeeeettttssss and rrrreeeeaaaadddd commands
  48.      can return without blocking.  A file is also considered to be readable if
  49.      an end-of-file or error condition is present.  It is important for _s_c_r_i_p_t
  50.      to check for these conditions and handle them appropriately;  for
  51.      example, if there is no special check for end-of-file, an infinite loop
  52.      may occur where _s_c_r_i_p_t reads no data, returns, and is immediately invoked
  53.      again.
  54.  
  55.      When using ffffiiiilllleeeeeeeevvvveeeennnntttt for event-driven I/O, it's important to read the
  56.      file in the same units that are written from the other end.  For example,
  57.      suppose that you are using ffffiiiilllleeeeeeeevvvveeeennnntttt to read data generated by a child
  58.      process.  If the child process is writing whole lines, then you should
  59.      use ggggeeeettttssss to read those lines.  If the child generates one line at a time
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ffffiiiilllleeeeeeeevvvveeeennnntttt((((3333TTTTkkkk))))                                                  ffffiiiilllleeeeeeeevvvveeeennnntttt((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.      then you shouldn't make more than a single call to ggggeeeettttssss in _s_c_r_i_p_t: the
  75.      first call will consume all the available data, so the second call may
  76.      block.  You can also use rrrreeeeaaaadddd to read the child's data, but only if you
  77.      know how many bytes the child is writing at a time:  if you try to read
  78.      more bytes than the child has written, the rrrreeeeaaaadddd call will block.
  79.  
  80.      A file is considered to be writable if at least one byte of data can be
  81.      written to the file without blocking, or if an error condition is
  82.      present.  Write handlers are probably not very useful without additional
  83.      command support.  The ppppuuuuttttssss command is dangerous since it write more than
  84.      one byte at a time and may thus block.  What is really needed is a new
  85.      non-blocking form of write that saves any data that couldn't be written
  86.      to the file.
  87.  
  88.      The script for a file event is executed at global level (outside the
  89.      context of any Tcl procedure).  If an error occurs while executing the
  90.      script then the ttttkkkkeeeerrrrrrrroooorrrr mechanism is used to report the error.  In
  91.      addition, the file event handler is deleted if it ever returns an error;
  92.      this is done in order to prevent infinite loops due to buggy handlers.
  93.  
  94.  
  95. CCCCRRRREEEEDDDDIIIITTTTSSSS
  96.      ffffiiiilllleeeeeeeevvvveeeennnntttt is based on the aaaaddddddddiiiinnnnppppuuuutttt command created by Mark Diekhans.
  97.  
  98.  
  99. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  100.      tkerror
  101.  
  102.  
  103. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  104.      asynchronous I/O, event handler, file, readable, script, writable
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.